home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / QD3DCamera.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  11.0 KB  |  387 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        QD3DCamera.h
  3.  
  4.      Contains:    Generic camera routines                                             
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.6
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1995-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DCAMERA__
  18. #define __QD3DCAMERA__
  19.  
  20. #ifndef __QD3D__
  21.     #include <QD3D.h>
  22. #endif
  23.  
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=power
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47. #if PRAGMA_ENUM_ALWAYSINT
  48.     #pragma enumsalwaysint on
  49. #elif PRAGMA_ENUM_OPTIONS
  50.     #pragma option enum=int
  51. #elif PRAGMA_ENUM_PACK
  52.     #if __option(pack_enums)
  53.         #define PRAGMA_ENUM_PACK__QD3DCAMERA__
  54.     #endif
  55.     #pragma options(!pack_enums)
  56. #endif
  57.  
  58. /******************************************************************************
  59.  **                                                                             **
  60.  **                            Data Structure Definitions                         **
  61.  **                                                                             **
  62.  *****************************************************************************/
  63. /*
  64.  *  The placement of the camera.
  65.  */
  66.  
  67. struct TQ3CameraPlacement {
  68.     TQ3Point3D                         cameraLocation;                /*  Location point of the camera     */
  69.     TQ3Point3D                         pointOfInterest;            /*  Point of interest                 */
  70.     TQ3Vector3D                     upVector;                    /*  "up" vector                     */
  71. };
  72. typedef struct TQ3CameraPlacement        TQ3CameraPlacement;
  73. /*
  74.  *  The range of the camera.
  75.  */
  76.  
  77. struct TQ3CameraRange {
  78.     float                             hither;                        /*  Hither plane, measured from "from" towards "to"    */
  79.     float                             yon;                        /*  Yon  plane, measured from "from" towards "to"     */
  80. };
  81. typedef struct TQ3CameraRange            TQ3CameraRange;
  82. /*
  83.  *  Viewport specification.  Origin is (-1, 1), and corresponds to the 
  84.  *  upper left-hand corner; width and height maximum is (2.0, 2.0),
  85.  *  corresponding to the lower left-hand corner of the window.  The
  86.  *  TQ3Viewport specifies a part of the viewPlane that gets displayed 
  87.  *    on the window that is to be drawn.
  88.  *  Normally, it is set with an origin of (-1.0, 1.0), and a width and
  89.  *  height of both 2.0, specifying that the entire window is to be
  90.  *  drawn.  If, for example, an exposure event of the window exposed
  91.  *  the right half of the window, you would set the origin to (0, 1),
  92.  *  and the width and height to (1.0) and (2.0), respectively.
  93.  *
  94.  */
  95.  
  96. struct TQ3CameraViewPort {
  97.     TQ3Point2D                         origin;
  98.     float                             width;
  99.     float                             height;
  100. };
  101. typedef struct TQ3CameraViewPort        TQ3CameraViewPort;
  102.  
  103. struct TQ3CameraData {
  104.     TQ3CameraPlacement                 placement;
  105.     TQ3CameraRange                     range;
  106.     TQ3CameraViewPort                 viewPort;
  107. };
  108. typedef struct TQ3CameraData            TQ3CameraData;
  109. /*
  110.  *  An orthographic camera.
  111.  *
  112.  *  The lens characteristics are set with the dimensions of a
  113.  *  rectangular viewPort in the frame of the camera.
  114.  */
  115.  
  116. struct TQ3OrthographicCameraData {
  117.     TQ3CameraData                     cameraData;
  118.     float                             left;
  119.     float                             top;
  120.     float                             right;
  121.     float                             bottom;
  122. };
  123. typedef struct TQ3OrthographicCameraData TQ3OrthographicCameraData;
  124. /*
  125.  *  A perspective camera specified in terms of an arbitrary view plane.
  126.  *
  127.  *  This is most useful when setting the camera to look at a particular
  128.  *  object.  The viewPlane is set to distance from the camera to the object.
  129.  *  The halfWidth is set to half the width of the cross section of the object,
  130.  *  and the halfHeight equal to the halfWidth divided by the aspect ratio
  131.  *  of the viewPort.
  132.  * 
  133.  *  This is the only perspective camera with specifications for off-axis
  134.  *  viewing, which is desirable for scrolling.
  135.  */
  136.  
  137. struct TQ3ViewPlaneCameraData {
  138.     TQ3CameraData                     cameraData;
  139.     float                             viewPlane;
  140.     float                             halfWidthAtViewPlane;
  141.     float                             halfHeightAtViewPlane;
  142.     float                             centerXOnViewPlane;
  143.     float                             centerYOnViewPlane;
  144. };
  145. typedef struct TQ3ViewPlaneCameraData    TQ3ViewPlaneCameraData;
  146. /*
  147.  *    A view angle aspect camera is a perspective camera specified in 
  148.  *    terms of the minimum view angle and the aspect ratio of X to Y.
  149.  *
  150.  */
  151.  
  152. struct TQ3ViewAngleAspectCameraData {
  153.     TQ3CameraData                     cameraData;
  154.     float                             fov;
  155.     float                             aspectRatioXToY;
  156. };
  157. typedef struct TQ3ViewAngleAspectCameraData TQ3ViewAngleAspectCameraData;
  158. /******************************************************************************
  159.  **                                                                             **
  160.  **                            Generic Camera routines                             **
  161.  **                                                                             **
  162.  *****************************************************************************/
  163.  
  164. EXTERN_API_C( TQ3ObjectType )
  165. Q3Camera_GetType                (TQ3CameraObject         camera);
  166.  
  167. EXTERN_API_C( TQ3Status )
  168. Q3Camera_SetData                (TQ3CameraObject         camera,
  169.                                  const TQ3CameraData *    cameraData);
  170.  
  171. EXTERN_API_C( TQ3Status )
  172. Q3Camera_GetData                (TQ3CameraObject         camera,
  173.                                  TQ3CameraData *        cameraData);
  174.  
  175. EXTERN_API_C( TQ3Status )
  176. Q3Camera_SetPlacement            (TQ3CameraObject         camera,
  177.                                  const TQ3CameraPlacement * placement);
  178.  
  179. EXTERN_API_C( TQ3Status )
  180. Q3Camera_GetPlacement            (TQ3CameraObject         camera,
  181.                                  TQ3CameraPlacement *    placement);
  182.  
  183. EXTERN_API_C( TQ3Status )
  184. Q3Camera_SetRange                (TQ3CameraObject         camera,
  185.                                  const TQ3CameraRange *    range);
  186.  
  187. EXTERN_API_C( TQ3Status )
  188. Q3Camera_GetRange                (TQ3CameraObject         camera,
  189.                                  TQ3CameraRange *        range);
  190.  
  191. EXTERN_API_C( TQ3Status )
  192. Q3Camera_SetViewPort            (TQ3CameraObject         camera,
  193.                                  const TQ3CameraViewPort * viewPort);
  194.  
  195. EXTERN_API_C( TQ3Status )
  196. Q3Camera_GetViewPort            (TQ3CameraObject         camera,
  197.                                  TQ3CameraViewPort *    viewPort);
  198.  
  199. EXTERN_API_C( TQ3Status )
  200. Q3Camera_GetWorldToView            (TQ3CameraObject         camera,
  201.                                  TQ3Matrix4x4 *            worldToView);
  202.  
  203. EXTERN_API_C( TQ3Status )
  204. Q3Camera_GetWorldToFrustum        (TQ3CameraObject         camera,
  205.                                  TQ3Matrix4x4 *            worldToFrustum);
  206.  
  207. EXTERN_API_C( TQ3Status )
  208. Q3Camera_GetViewToFrustum        (TQ3CameraObject         camera,
  209.                                  TQ3Matrix4x4 *            viewToFrustum);
  210.  
  211.  
  212. /******************************************************************************
  213.  **                                                                             **
  214.  **                            Specific Camera Routines                          **
  215.  **                                                                             **
  216.  *****************************************************************************/
  217. /******************************************************************************
  218.  **                                                                             **
  219.  **                            Orthographic Camera                                  **
  220.  **                                                                             **
  221.  *****************************************************************************/
  222. EXTERN_API_C( TQ3CameraObject )
  223. Q3OrthographicCamera_New        (const TQ3OrthographicCameraData * orthographicData);
  224.  
  225. EXTERN_API_C( TQ3Status )
  226. Q3OrthographicCamera_GetData    (TQ3CameraObject         camera,
  227.                                  TQ3OrthographicCameraData * cameraData);
  228.  
  229. EXTERN_API_C( TQ3Status )
  230. Q3OrthographicCamera_SetData    (TQ3CameraObject         camera,
  231.                                  const TQ3OrthographicCameraData * cameraData);
  232.  
  233. EXTERN_API_C( TQ3Status )
  234. Q3OrthographicCamera_SetLeft    (TQ3CameraObject         camera,
  235.                                  float                     left);
  236.  
  237. EXTERN_API_C( TQ3Status )
  238. Q3OrthographicCamera_GetLeft    (TQ3CameraObject         camera,
  239.                                  float *                left);
  240.  
  241. EXTERN_API_C( TQ3Status )
  242. Q3OrthographicCamera_SetTop        (TQ3CameraObject         camera,
  243.                                  float                     top);
  244.  
  245. EXTERN_API_C( TQ3Status )
  246. Q3OrthographicCamera_GetTop        (TQ3CameraObject         camera,
  247.                                  float *                top);
  248.  
  249. EXTERN_API_C( TQ3Status )
  250. Q3OrthographicCamera_SetRight    (TQ3CameraObject         camera,
  251.                                  float                     right);
  252.  
  253. EXTERN_API_C( TQ3Status )
  254. Q3OrthographicCamera_GetRight    (TQ3CameraObject         camera,
  255.                                  float *                right);
  256.  
  257. EXTERN_API_C( TQ3Status )
  258. Q3OrthographicCamera_SetBottom    (TQ3CameraObject         camera,
  259.                                  float                     bottom);
  260.  
  261. EXTERN_API_C( TQ3Status )
  262. Q3OrthographicCamera_GetBottom    (TQ3CameraObject         camera,
  263.                                  float *                bottom);
  264.  
  265.  
  266. /******************************************************************************
  267.  **                                                                             **
  268.  **                            ViewPlane Camera                                  **
  269.  **                                                                             **
  270.  *****************************************************************************/
  271. EXTERN_API_C( TQ3CameraObject )
  272. Q3ViewPlaneCamera_New            (const TQ3ViewPlaneCameraData * cameraData);
  273.  
  274. EXTERN_API_C( TQ3Status )
  275. Q3ViewPlaneCamera_GetData        (TQ3CameraObject         camera,
  276.                                  TQ3ViewPlaneCameraData * cameraData);
  277.  
  278. EXTERN_API_C( TQ3Status )
  279. Q3ViewPlaneCamera_SetData        (TQ3CameraObject         camera,
  280.                                  const TQ3ViewPlaneCameraData * cameraData);
  281.  
  282. EXTERN_API_C( TQ3Status )
  283. Q3ViewPlaneCamera_SetViewPlane    (TQ3CameraObject         camera,
  284.                                  float                     viewPlane);
  285.  
  286. EXTERN_API_C( TQ3Status )
  287. Q3ViewPlaneCamera_GetViewPlane    (TQ3CameraObject         camera,
  288.                                  float *                viewPlane);
  289.  
  290. EXTERN_API_C( TQ3Status )
  291. Q3ViewPlaneCamera_SetHalfWidth    (TQ3CameraObject         camera,
  292.                                  float                     halfWidthAtViewPlane);
  293.  
  294. EXTERN_API_C( TQ3Status )
  295. Q3ViewPlaneCamera_GetHalfWidth    (TQ3CameraObject         camera,
  296.                                  float *                halfWidthAtViewPlane);
  297.  
  298. EXTERN_API_C( TQ3Status )
  299. Q3ViewPlaneCamera_SetHalfHeight    (TQ3CameraObject         camera,
  300.                                  float                     halfHeightAtViewPlane);
  301.  
  302. EXTERN_API_C( TQ3Status )
  303. Q3ViewPlaneCamera_GetHalfHeight    (TQ3CameraObject         camera,
  304.                                  float *                halfHeightAtViewPlane);
  305.  
  306. EXTERN_API_C( TQ3Status )
  307. Q3ViewPlaneCamera_SetCenterX    (TQ3CameraObject         camera,
  308.                                  float                     centerXOnViewPlane);
  309.  
  310. EXTERN_API_C( TQ3Status )
  311. Q3ViewPlaneCamera_GetCenterX    (TQ3CameraObject         camera,
  312.                                  float *                centerXOnViewPlane);
  313.  
  314. EXTERN_API_C( TQ3Status )
  315. Q3ViewPlaneCamera_SetCenterY    (TQ3CameraObject         camera,
  316.                                  float                     centerYOnViewPlane);
  317.  
  318. EXTERN_API_C( TQ3Status )
  319. Q3ViewPlaneCamera_GetCenterY    (TQ3CameraObject         camera,
  320.                                  float *                centerYOnViewPlane);
  321.  
  322.  
  323. /******************************************************************************
  324.  **                                                                             **
  325.  **                            View Angle Aspect Camera                          **
  326.  **                                                                             **
  327.  *****************************************************************************/
  328. EXTERN_API_C( TQ3CameraObject )
  329. Q3ViewAngleAspectCamera_New        (const TQ3ViewAngleAspectCameraData * cameraData);
  330.  
  331. EXTERN_API_C( TQ3Status )
  332. Q3ViewAngleAspectCamera_SetData    (TQ3CameraObject         camera,
  333.                                  const TQ3ViewAngleAspectCameraData * cameraData);
  334.  
  335. EXTERN_API_C( TQ3Status )
  336. Q3ViewAngleAspectCamera_GetData    (TQ3CameraObject         camera,
  337.                                  TQ3ViewAngleAspectCameraData * cameraData);
  338.  
  339. EXTERN_API_C( TQ3Status )
  340. Q3ViewAngleAspectCamera_SetFOV    (TQ3CameraObject         camera,
  341.                                  float                     fov);
  342.  
  343. EXTERN_API_C( TQ3Status )
  344. Q3ViewAngleAspectCamera_GetFOV    (TQ3CameraObject         camera,
  345.                                  float *                fov);
  346.  
  347. EXTERN_API_C( TQ3Status )
  348. Q3ViewAngleAspectCamera_SetAspectRatio (TQ3CameraObject  camera,
  349.                                  float                     aspectRatioXToY);
  350.  
  351. EXTERN_API_C( TQ3Status )
  352. Q3ViewAngleAspectCamera_GetAspectRatio (TQ3CameraObject  camera,
  353.                                  float *                aspectRatioXToY);
  354.  
  355.  
  356.  
  357.  
  358.  
  359. #if PRAGMA_ENUM_ALWAYSINT
  360.     #pragma enumsalwaysint reset
  361. #elif PRAGMA_ENUM_OPTIONS
  362.     #pragma option enum=reset
  363. #elif defined(PRAGMA_ENUM_PACK__QD3DCAMERA__)
  364.     #pragma options(pack_enums)
  365. #endif
  366.  
  367. #if PRAGMA_STRUCT_ALIGN
  368.     #pragma options align=reset
  369. #elif PRAGMA_STRUCT_PACKPUSH
  370.     #pragma pack(pop)
  371. #elif PRAGMA_STRUCT_PACK
  372.     #pragma pack()
  373. #endif
  374.  
  375. #ifdef PRAGMA_IMPORT_OFF
  376. #pragma import off
  377. #elif PRAGMA_IMPORT
  378. #pragma import reset
  379. #endif
  380.  
  381. #ifdef __cplusplus
  382. }
  383. #endif
  384.  
  385. #endif /* __QD3DCAMERA__ */
  386.  
  387.